TRGdos developer's documentation.

January 29, 2001.

Harry Konstas
hkonstas@total.net

You can visit my web site for updates:
http://www.total.net/~hkonstas



IMPORTANT UPGRADE INFORMATION:

If you have written a TRGdos application for TRGdos v.1.1 and below, you must
recompile your application by adding a tFrm 1000 resource in your executable.
This fixes the fatal error that PalmOS was giving when the user was enabling
the popup keyboard.


* The included developer's source code is written for the
  OnBoardC compiler (www.individeo.net)

* UTIL.ZIP contains additional (non standard) functions that you may
  find usefull for your applications.


A) TRGdos application guidelines
---------------------------------
TRGdos applications use a 40x26 character screen for output
and command line input via graffiti or external keyboard.


Here are some guidelines when creating TRGdos applications:


1.Include OBLstdio.c in your application's project file (.PRJ).

2.Include the OBLstdio.h header file at the beginning of 
  your source code.

3.Your application must be of type 'pdos' and have the
  creator ID of 'pDOS'

4.Handle malloc() with care - PalmOS reserves very little
  RAM and stack space for a running application.

5.Name your application in all small letters (no capitals).
  The reason is that PalmOS filenames are case sensitive.

6.Append ".EXE" to your application name.

7.Use a "press any key to continue" mechanism before your program
  ends, if it has important residual information on the screen 
  (PalmOS erases the screen when an application quits).

8.You can only pass up to 15 parameters to your application
  from the TRGdos command line.

9.Include a user abort mechanism on time consuming routines. The 
  reason is that while your application is doing a lengthy operation,
  PalmOS has no control of the hardware - thus the power button and
  the hardware buttons won't respond. PalmOS is called while TRGdos
  waits for user input only (gets() and getc() routines). You can use
  the UserAbort() function which polls for user intervention without
  blocking the program flow (non blocking).

10. Your application must have a tFrm 1000 resource and a tFnt resource
    (you can copy & paste them from demol.exe.prc


11.Use the 'cfcard' global variable to test the presence of a CF card/slot,
   if your application is using it. This variable returns 1 if card is present,
   0 otherwise.

* You can use the included demo source code and project file as a 
  template to start a new TRGdos application.



B) TRGdos currently available (standard) library functions
-----------------------------------------------------------


1.Keyboard input functions:
----------------------------------------------------------------------------
 Function : char *gets(char *buffer);
 Details  : Waits for the user to enter a string from the keyboard.
            Input is terminated by ENTER.
----------------------------------------------------------------------------
 Function : char getch(void);
 Details  : Waits for the user press a keyboard button and returns
            the pressed key (via graffiti)
----------------------------------------------------------------------------


2.Screen output functions:
----------------------------------------------------------------------------
 Function : printf(char *fmt,...);
 Details  : standard printf function
----------------------------------------------------------------------------
 Function : void putch(char c);
 Details  : print the character c on the screen.
----------------------------------------------------------------------------
 Function : void puts(char *s);
 Details  : print the string s on the screen.
----------------------------------------------------------------------------
 Function : void clrscr(void);
 Details  : clear the screen.
----------------------------------------------------------------------------
 Function : void gotoxy(int x,int y);
 Details  : position the cursor at x,y screen coordinates.
----------------------------------------------------------------------------


3.String functions:
----------------------------------------------------------------------------
 Function : char *itoa(int v,char *buffer,int base);
 Details  : Return a string representation of an integer. The 'base'
            value is ignored.
----------------------------------------------------------------------------
 Function : char *ltoa(long v,char*buffer,int base);
 Details  : Return a string representation of a long integer
----------------------------------------------------------------------------
 Function : char *strcat(char *d,char *s);
 Details  : Appends string 's' to string 'd' and returns a pointer to 'd'
----------------------------------------------------------------------------
 Function : char *strcpy(char *d,char *s);
 Details  : Copies string 's' to string 'd'. Returns pointer to 'd'
----------------------------------------------------------------------------
 Function : char *strupr(char *s);
 Details  : Converts 's' to upper case. Returns pointer to converted 's'
----------------------------------------------------------------------------
 Function : int  atoi(char *buffer);
 Details  : Return integer value of string
----------------------------------------------------------------------------
 Function : int strlen(char *s);
 Details  : Returns the size of the given string
----------------------------------------------------------------------------
 Function : int strstr(char *s, char *k);
 Details  : Checks if string k is included in string s. Returns true
            if it is.
----------------------------------------------------------------------------
 Function : long atol(char *s);
 Details  : Converts string 's' to long. Returns long integer
----------------------------------------------------------------------------
 Function : int strcmp(char *s1,char *s2);
 Details  : Compare strings s1 and s2.

Returns:
  0: s1==s2
  1: s1>s2
 -1: s1<s2
----------------------------------------------------------------------------
 Function : char *ftoa(float f, char *buf);
 Details  : Convert float to string (prec:2 decimals)
----------------------------------------------------------------------------
 Function : float atof(char *s);
 Details  : Convert string to float
----------------------------------------------------------------------------


4.Memory allocation functions: 
----------------------------------------------------------------------------
 Function : void *malloc(int size);
 Details  : allocate 'size' bytes of memory. Handle with
            care! Palm allocates little memory to the running application.
----------------------------------------------------------------------------
 Function : void free(void *p);
 Details  : free previously allocated memory with malloc()
----------------------------------------------------------------------------


5.Floating point functions:
----------------------------------------------------------------------------
 Function : char *ftoa(float f, char *buf);
 Details  : Convert float to string (prec:2 decimals)
----------------------------------------------------------------------------
 Function : float atof(char *s);
 Details  : Convert string to float
----------------------------------------------------------------------------
 Function : float fabs(float f);
 Details  : return absolute value of float
----------------------------------------------------------------------------


6.File operation functions
----------------------------------------------------------------------------
 Function : int close(int h);
 Details  : Close a file with the given handle.  Works on CF card only.
----------------------------------------------------------------------------
 Function : int open(char *fname, int flags, int mode);
 Details  : Open a file, return handle.  Works on CF card only.

Flags:
O_RDONLY  0x0000   Open for read only                       
O_WRONLY  0x0001   Open for write only 
O_RDWR    0x0002   Read/write access allowed.   
O_APPEND  0x0008   Seek to eof on each write 
O_CREAT   0x0100   Create the file if it does not exist. 
O_BINARY  0x8000   Ignored. All file access is binary   

Modes:
S_IREAD   0000200  Read permitted. (Always true anyway)  
S_IWRITE  0000400  Write permitted               

----------------------------------------------------------------------------
 Function : int read(int h,void *buf,int size);
 Details  : Read 'size' bytes from 'h' file handle into
            buffer. Returns #of bytes read.

 Works on CF card only.
----------------------------------------------------------------------------
 Function : int remove(char *fname);
 Details  : Delete a file on the CF card
----------------------------------------------------------------------------
 Function : int rename(char *oldname,char *newname);
 Details  : Rename a file in CF card
----------------------------------------------------------------------------
 Function : int write(int h,void *buf,int size);
 Details  : Write 'size' bytes to 'h' file handle from buffer. Returns
            #of bytes written.  Works on CF card only.
----------------------------------------------------------------------------
 Function : long lseek(int h,long offset,int origin);
 Details  : Seek the 'h' file pointer to the specified direction and origin.

SEEK_SET   0  offset from begining of file  
SEEK_CUR   1  offset from current file pointer 

SEEK_END   2  offset from end of file

----------------------------------------------------------------------------


7.Other functions:

----------------------------------------------------------------------------
 Function : char *getdate(char *s);
 Details  : returns the current date in string 's'
----------------------------------------------------------------------------
 Function : beep(void);
 Details  : beeps the speaker
----------------------------------------------------------------------------
 Function : int UserAbort(void);
 Details  : returns 1 if the user taps left side of the graffiti area.
----------------------------------------------------------------------------


8.Directory operation functions (standard):

int findfirst(char *mask, ffblk *stat, int flags)
int findnext(ffblk *stat)

Create a dirextory:
int mkdir(char *dirname)

Delete a directory:
int rmdir(char *dirname)

Change directory:
int chdir(char *path)

Get current working directory:
char *getcwd(char *buf, int buflen)

Get disk free space:
void getdfree(unsigned char drive, diskfree_t *dtable)


